첫 발화 한국어 유도 개선 가이드

마지막 업데이트 2026-07-29

2025-05-19 · PPI-955 · 요구사항 검토용 (세부 내용 변경 가능)

💬 대화로 먼저 이해하기 — "연극 대본 비유" (비개발자·처음 읽는 사람용)

Q이 문서는 무엇을 다루나요?

A세션 첫 발화에서 핑퐁이가 가끔 영어를 섞거나 시작 멘트를 이상하게 변형하는 문제(PPI-955)를 어떻게 고칠지, 개선 아이디어 2가지를 비교 검토하는 가이드예요. 확정 설계가 아니라 검토 단계 문서입니다.

Q왜 그런 문제가 생긴 거예요?

A배우(AI)에게 "이 대사를 토씨 하나 안 틀리고 그대로 읽어"라고 지시하는 게 현재 방식인데, 이 지시가 배우가 이미 받은 캐릭터 설정(personality 지침)과 충돌하면 대사가 오히려 어색하게 변형되거나 영어가 섞여 나와요.

Q그럼 어떻게 바꾸자는 건가요?

A아이디어 1은 대사 지정 자체를 포기하고 "한국어로만 시작해"라는 연출 방향만 주는 것, 아이디어 2는 "그대로 읽어"를 "시작 멘트는 이거야" 정도로 지시 강도를 낮추는 거예요. 모니터 대시보드의 라디오 버튼으로 두 방식을 실제 수업에서 번갈아 A/B 테스트합니다.

Q읽을 때 뭘 기준으로 판단하면 되나요?

A"영어 발화가 없어지는가"와 "시작 멘트가 변형되지 않는가" 두 조건이 동시에 만족돼야 해요. 각 아이디어의 검증 체크리스트와 문서 끝의 "검토 시 참고사항"을 기준으로 보세요.

AS-IS 현재 방식 & 문제

세션이 시작되면 response.create의 instructions 필드로 첫 발화 지침을 전달합니다. 프롬프트의 "시작" 키 값을 파싱하여 강제 발화 문구를 만들어 냅니다.

// use-ai-session.ts — 현재 코드 (라인 1124–1128)
responseInstructions: firstTurnKoreanGuideEnabled
  ? firstResponseText
    ? `이것은 대화의 첫 번째 차례(시작 단계)입니다. 반드시 한국어로, 다음 문장을 수정 없이 그대로 말하세요: "${firstResponseText}"`
    : `반드시 한국어로만 대화를 시작하세요.`
  : undefined,

데이터 흐름

activity.variables["시작"] 또는 instruction 본문에서 "시작": "값" 파싱

프리셋 변수 치환 (replaceInstructionVariables)

response.create.instructions에 "그대로 말하세요" 지침 주입

확인된 문제

케이스	현상	원인 추정
"안녕?" + 어른스러운 멘트	시작 멘트가 변형됨 (영어 발화 포함)	"그대로 말하세요" 지침이 personality 지침과 충돌
기타 특징 있는 멘트	전수조사 미완료, 추가 케이스 예측 불가	동일 원인 추정

파싱 제거 — 한국어 지침만

시작멘트 파싱 로직을 완전히 제거하고, 한국어로만 시작하라는 지침만 남깁니다

BEFORE

firstResponseText
  ? `이것은 대화의 첫 번째 차례...
    반드시 한국어로, 다음 문장을
    수정 없이 그대로 말하세요:
    "${firstResponseText}"`
  : `반드시 한국어로만 대화를
    시작하세요.`

AFTER

// 파싱 없음 — 지침만
`반드시 한국어로만 대화를
 시작하세요.`

변경 영향 범위

use-ai-session.ts — rawFirstResponseText 파싱 블록 제거
prompt-test.tsx — 동일한 파싱 블록 제거
DB / API / Store — 변경 없음

⚠️ 시작멘트를 세밀하게 제어하고 싶은 경우 이 방식으로는 불가합니다. 테스트 목적으로 먼저 검증 후 영구 적용 여부를 결정하세요.

검증 체크리스트

영어 발화 없이 한국어로만 첫 발화가 시작되는가
personality 지침과 충돌 없이 시작 멘트가 자연스럽게 나오는가
"안녕?" + 어른스러운 멘트 케이스에서 변형 없이 동작하는가
시작멘트가 없는 activity에서도 정상 동작하는가
프롬프트 테스트 페이지에서도 동일하게 동작하는가

지침 문구 변경 — 부드럽게 풀기

"그대로 말해" 대신 "한국어로 시작해. 시작 멘트: ~~~" 형태로 완화

BEFORE

`이것은 대화의 첫 번째 차례...
반드시 한국어로,
다음 문장을 수정 없이
그대로 말하세요:
"${firstResponseText}"`

AFTER

`반드시 한국어로 첫 발화를
시작해. 시작 멘트 :
"${firstResponseText}"`

문구 대응표

상황	기존 지침	새 지침
시작멘트 있음	이것은 대화의 첫 번째 차례입니다. 반드시 한국어로, 다음 문장을 수정 없이 그대로 말하세요: "..."	반드시 한국어로 첫 발화를 시작해. 시작 멘트 : "..."
시작멘트 없음	반드시 한국어로만 대화를 시작하세요.	(동일) 반드시 한국어로만 대화를 시작하세요.

변경 영향 범위

use-ai-session.ts — 지침 문자열만 수정
prompt-test.tsx — 동일한 지침 문자열 수정
DB / API / Store — 변경 없음

검증 체크리스트

영어 발화 없이 한국어로만 첫 발화가 시작되는가
시작멘트가 의도한 내용으로 발화되는가 (완전 동일하지 않아도 되는지 확인)
"안녕?" + 어른스러운 멘트 케이스에서 변형이 줄었는가
personality 지침과의 충돌이 완화되었는가
시작멘트가 없는 activity에서 fallback 동작이 정상인가

UI 검증 모니터 대시보드 — 방식 선택 UI

아이디어를 실제로 비교 테스트할 수 있도록, 첫발화 한국어 유도 섹션에 방식 선택 라디오 버튼을 추가합니다.

🖥 모니터 대시보드 — 첫발화 한국어 유도 섹션 (UI 목업)

첫발화 한국어 유도

AI 세션 시작 시 첫 번째 발화 응답에 한국어 유도 지시문을 포함합니다.

감지 활성화

ON 시 세션 첫 응답에 한국어로 시작하도록 지시문이 추가됩니다.

지침 방식 선택

현재 방식 (AS-IS)

시작멘트 파싱 후 "수정 없이 그대로 말하세요" 지침

아이디어 1 — 한국어 지침만

파싱 없이 "반드시 한국어로만 대화를 시작하세요"만 전달

아이디어 2 — 새 문구

"반드시 한국어로 첫 발화를 시작해. 시작 멘트 : ~~~"

설정값은 DynamoDB에 저장되어 모든 세션에 즉시 반영됩니다. 아이디어 1·2를 번갈아 선택하며 실제 수업 세션에서 비교 테스트할 수 있습니다.

구현 변경 파일 목록

파일	변경 내용
`types/db/first-turn-korean-guide.types.ts`	`KoreanGuideApproach` 타입 추가, Settings에 approach 필드 추가
`stores/use-first-turn-korean-guide-store.ts`	approach 상태 및 setApproach 액션 추가
`app/api/first-turn-korean-guide-settings/route.ts`	PUT 핸들러에서 approach 필드 처리
`lib/db-queries.ts`	updateFirstTurnKoreanGuideSettings 함수 추가
`components/sections/first-turn-korean-guide-section.tsx`	방식 선택 라디오 버튼 UI 추가
`entities/guest-session/model/use-ai-session.ts`	approach에 따라 responseInstructions 분기
`components/pages/prompt-test.tsx`	동일한 approach 분기 적용

주의 검토 시 참고사항

이 문서는 검토 단계이며, 세부 요구사항은 변경될 수 있습니다.
아이디어 1·2는 순서대로 테스트하되 결과에 따라 하나만 채택하거나 추가 방식을 모색할 수 있습니다.
"영어 발화 없어지는지"와 "첫발화 변형 없는지" 두 가지가 동시에 만족되어야 합니다.
아이디어 1은 시작멘트 내용에 대한 제어를 포기하므로, personality와의 조화를 최우선으로 확인하세요.
아이디어 2는 파싱은 유지하되 지침 강도를 낮추므로, 시작멘트가 완전 동일하게 나오지 않을 수 있습니다.

생성일: 2025-05-19 · PPI-955